home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / include / nss / ocspti.h < prev    next >
C/C++ Source or Header  |  2006-04-20  |  16KB  |  409 lines
  1. /* ***** BEGIN LICENSE BLOCK *****
  2.  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  3.  *
  4.  * The contents of this file are subject to the Mozilla Public License Version
  5.  * 1.1 (the "License"); you may not use this file except in compliance with
  6.  * the License. You may obtain a copy of the License at
  7.  * http://www.mozilla.org/MPL/
  8.  *
  9.  * Software distributed under the License is distributed on an "AS IS" basis,
  10.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  11.  * for the specific language governing rights and limitations under the
  12.  * License.
  13.  *
  14.  * The Original Code is the Netscape security libraries.
  15.  *
  16.  * The Initial Developer of the Original Code is
  17.  * Netscape Communications Corporation.
  18.  * Portions created by the Initial Developer are Copyright (C) 1994-2000
  19.  * the Initial Developer. All Rights Reserved.
  20.  *
  21.  * Contributor(s):
  22.  *
  23.  * Alternatively, the contents of this file may be used under the terms of
  24.  * either the GNU General Public License Version 2 or later (the "GPL"), or
  25.  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  26.  * in which case the provisions of the GPL or the LGPL are applicable instead
  27.  * of those above. If you wish to allow use of your version of this file only
  28.  * under the terms of either the GPL or the LGPL, and not to allow others to
  29.  * use your version of this file under the terms of the MPL, indicate your
  30.  * decision by deleting the provisions above and replace them with the notice
  31.  * and other provisions required by the GPL or the LGPL. If you do not delete
  32.  * the provisions above, a recipient may use your version of this file under
  33.  * the terms of any one of the MPL, the GPL or the LGPL.
  34.  *
  35.  * ***** END LICENSE BLOCK ***** */
  36.  
  37. /*
  38.  * Private header defining OCSP types.
  39.  *
  40.  * $Id: ocspti.h,v 1.5 2004/04/25 15:03:03 gerv%gerv.net Exp $
  41.  */
  42.  
  43. #ifndef _OCSPTI_H_
  44. #define _OCSPTI_H_
  45.  
  46. #include "ocspt.h"
  47.  
  48. #include "certt.h"
  49. #include "plarena.h"
  50. #include "seccomon.h"
  51. #include "secoidt.h"
  52.  
  53.  
  54. /*
  55.  * Some notes about naming conventions...
  56.  *
  57.  * The public data types all start with "CERTOCSP" (e.g. CERTOCSPRequest).
  58.  * (Even the public types are opaque, however.  Only their names are
  59.  * "exported".)
  60.  *
  61.  * Internal-only data types drop the "CERT" prefix and use only the
  62.  * lower-case "ocsp" (e.g. ocspTBSRequest), for brevity sake.
  63.  *
  64.  * In either case, the base/suffix of the type name usually matches the
  65.  * name as defined in the OCSP specification.  The exceptions to this are:
  66.  *  - When there is overlap between the "OCSP" or "ocsp" prefix and
  67.  *    the name used in the standard.  That is, you cannot strip off the
  68.  *    "CERTOCSP" or "ocsp" prefix and necessarily get the name of the
  69.  *    type as it is defined in the standard; the "real" name will be
  70.  *    *either* "OCSPSuffix" or just "Suffix".
  71.  *  - When the name in the standard was a little too generic.  (e.g. The
  72.  *    standard defines "Request" but we call it a "SingleRequest".)
  73.  *    In this case a comment above the type definition calls attention
  74.  *    to the difference.
  75.  *
  76.  * The definitions laid out in this header file are intended to follow
  77.  * the same order as the definitions in the OCSP specification itself.
  78.  * With the OCSP standard in hand, you should be able to move through
  79.  * this file and follow along.  To future modifiers of this file: please
  80.  * try to keep it that way.  The only exceptions are the few cases where
  81.  * we need to define a type before it is referenced (e.g. enumerations),
  82.  * whereas in the OCSP specification these are usually defined the other
  83.  * way around (reference before definition).
  84.  */
  85.  
  86.  
  87. /*
  88.  * Forward-declarations of internal-only data structures.
  89.  *
  90.  * These are in alphabetical order (case-insensitive); please keep it that way!
  91.  */
  92. typedef struct ocspBasicOCSPResponseStr ocspBasicOCSPResponse;
  93. typedef struct ocspCertStatusStr ocspCertStatus;
  94. typedef struct ocspResponderIDStr ocspResponderID;
  95. typedef struct ocspResponseBytesStr ocspResponseBytes;
  96. typedef struct ocspResponseDataStr ocspResponseData;
  97. typedef struct ocspRevokedInfoStr ocspRevokedInfo;
  98. typedef struct ocspServiceLocatorStr ocspServiceLocator;
  99. typedef struct ocspSignatureStr ocspSignature;
  100. typedef struct ocspSingleRequestStr ocspSingleRequest;
  101. typedef struct ocspSingleResponseStr ocspSingleResponse;
  102. typedef struct ocspTBSRequestStr ocspTBSRequest;
  103.  
  104.  
  105. /*
  106.  * An OCSPRequest; this is what is sent (encoded) to an OCSP responder.
  107.  */
  108. struct CERTOCSPRequestStr {
  109.     PRArenaPool *arena;            /* local; not part of encoding */
  110.     ocspTBSRequest *tbsRequest;
  111.     ocspSignature *optionalSignature;
  112. };
  113.  
  114. /*
  115.  * A TBSRequest; when an OCSPRequest is signed, the encoding of this
  116.  * is what the signature is actually applied to.  ("TBS" == To Be Signed)
  117.  * Whether signed or not, however, this structure will be present, and
  118.  * is the "meat" of the OCSPRequest.
  119.  *
  120.  * Note that the "requestorName" field cannot be encoded/decoded in the
  121.  * same pass as the entire request -- it needs to be handled with a special
  122.  * call to convert to/from our internal form of a GeneralName.  Thus the
  123.  * "derRequestorName" field, which is the actual DER-encoded bytes.
  124.  *
  125.  * The "extensionHandle" field is used on creation only; it holds
  126.  * in-progress extensions as they are optionally added to the request.
  127.  */
  128. struct ocspTBSRequestStr {
  129.     SECItem version;            /* an INTEGER */
  130.     SECItem *derRequestorName;        /* encoded GeneralName; see above */
  131.     CERTGeneralNameList *requestorName;    /* local; not part of encoding */
  132.     ocspSingleRequest **requestList;
  133.     CERTCertExtension **requestExtensions;
  134.     void *extensionHandle;        /* local; not part of encoding */
  135. };
  136.  
  137. /*
  138.  * This is the actual signature information for an OCSPRequest (applied to
  139.  * the TBSRequest structure) or for a BasicOCSPResponse (applied to a
  140.  * ResponseData structure).
  141.  *
  142.  * Note that the "signature" field itself is a BIT STRING; operations on
  143.  * it need to keep that in mind, converting the length to bytes as needed
  144.  * and back again afterward (so that the length is usually expressing bits).
  145.  *
  146.  * The "cert" field is the signer's certificate.  In the case of a received
  147.  * signature, it will be filled in when the signature is verified.  In the
  148.  * case of a created signature, it is filled in on creation and will be the
  149.  * cert used to create the signature when the signing-and-encoding occurs,
  150.  * as well as the cert (and its chain) to fill in derCerts if requested.
  151.  *
  152.  * The extra fields cache information about the signature after we have
  153.  * attempted a verification.  "wasChecked", if true, means the signature
  154.  * has been checked against the appropriate data and thus that "status"
  155.  * contains the result of that verification.  If "status" is not SECSuccess,
  156.  * "failureReason" is a copy of the error code that was set at the time;
  157.  * presumably it tells why the signature verification failed.
  158.  */
  159. struct ocspSignatureStr {
  160.     SECAlgorithmID signatureAlgorithm;
  161.     SECItem signature;            /* a BIT STRING */
  162.     SECItem **derCerts;            /* a SEQUENCE OF Certificate */
  163.     CERTCertificate *cert;        /* local; not part of encoding */
  164.     PRBool wasChecked;            /* local; not part of encoding */
  165.     SECStatus status;            /* local; not part of encoding */
  166.     int failureReason;            /* local; not part of encoding */
  167. };
  168.  
  169. /*
  170.  * An OCSPRequest contains a SEQUENCE OF these, one for each certificate
  171.  * whose status is being checked.
  172.  *
  173.  * Note that in the OCSP specification this is just called "Request",
  174.  * but since that seemed confusing (vs. an OCSPRequest) and to be more
  175.  * consistent with the parallel type "SingleResponse", I called it a
  176.  * "SingleRequest".
  177.  * 
  178.  * XXX figure out how to get rid of that arena -- there must be a way
  179.  */
  180. struct ocspSingleRequestStr {
  181.     PRArenaPool *arena;            /* just a copy of the response arena,
  182.                      * needed here for extension handling
  183.                      * routines, on creation only */
  184.     CERTOCSPCertID *reqCert;
  185.     CERTCertExtension **singleRequestExtensions;
  186. };
  187.  
  188. /*
  189.  * A CertID is the means of identifying a certificate, used both in requests
  190.  * and in responses.
  191.  *
  192.  * When in a SingleRequest it specifies the certificate to be checked.
  193.  * When in a SingleResponse it is the cert whose status is being given.
  194.  */
  195. struct CERTOCSPCertIDStr {
  196.     SECAlgorithmID hashAlgorithm;
  197.     SECItem issuerNameHash;        /* an OCTET STRING */
  198.     SECItem issuerKeyHash;        /* an OCTET STRING */
  199.     SECItem serialNumber;        /* an INTEGER */
  200.     SECItem issuerSHA1NameHash;        /* keep other hashes around when */
  201.     SECItem issuerMD5NameHash;              /* we have them */
  202.     SECItem issuerMD2NameHash;
  203.     SECItem issuerSHA1KeyHash;        /* keep other hashes around when */
  204.     SECItem issuerMD5KeyHash;              /* we have them */
  205.     SECItem issuerMD2KeyHash;
  206.     PRArenaPool *poolp;
  207. };
  208.  
  209. /*
  210.  * This describes the value of the responseStatus field in an OCSPResponse.
  211.  * The corresponding ASN.1 definition is:
  212.  *
  213.  * OCSPResponseStatus    ::=    ENUMERATED {
  214.  *    successful        (0),    --Response has valid confirmations
  215.  *    malformedRequest    (1),    --Illegal confirmation request
  216.  *    internalError        (2),    --Internal error in issuer
  217.  *    tryLater        (3),    --Try again later
  218.  *                    --(4) is not used
  219.  *    sigRequired        (5),    --Must sign the request
  220.  *    unauthorized        (6),    --Request unauthorized
  221.  * }
  222.  */
  223. typedef enum {
  224.     ocspResponse_successful = 0,
  225.     ocspResponse_malformedRequest = 1,
  226.     ocspResponse_internalError = 2,
  227.     ocspResponse_tryLater = 3,
  228.     ocspResponse_unused = 4,
  229.     ocspResponse_sigRequired = 5,
  230.     ocspResponse_unauthorized = 6,
  231.     ocspResponse_other            /* unknown/unrecognized value */
  232. } ocspResponseStatus;
  233.  
  234. /*
  235.  * An OCSPResponse is what is sent (encoded) by an OCSP responder.
  236.  *
  237.  * The field "responseStatus" is the ASN.1 encoded value; the field
  238.  * "statusValue" is simply that same value translated into our local
  239.  * type ocspResponseStatus.
  240.  */
  241. struct CERTOCSPResponseStr {
  242.     PRArenaPool *arena;            /* local; not part of encoding */
  243.     SECItem responseStatus;        /* an ENUMERATED, see above */
  244.     ocspResponseStatus statusValue;    /* local; not part of encoding */
  245.     ocspResponseBytes *responseBytes;    /* only when status is successful */
  246. };
  247.  
  248. /*
  249.  * A ResponseBytes (despite appearances) is what contains the meat
  250.  * of a successful response -- but still in encoded form.  The type
  251.  * given as "responseType" tells you how to decode the string.
  252.  *
  253.  * We look at the OID and translate it into our local OID representation
  254.  * "responseTypeTag", and use that value to tell us how to decode the
  255.  * actual response itself.  For now the only kind of OCSP response we
  256.  * know about is a BasicOCSPResponse.  However, the intention in the
  257.  * OCSP specification is to allow for other response types, so we are
  258.  * building in that flexibility from the start and thus put a pointer
  259.  * to that data structure inside of a union.  Whenever OCSP adds more
  260.  * response types, just add them to the union.
  261.  */
  262. struct ocspResponseBytesStr {
  263.     SECItem responseType;        /* an OBJECT IDENTIFIER */
  264.     SECOidTag responseTypeTag;        /* local; not part of encoding */
  265.     SECItem response;            /* an OCTET STRING */
  266.     union {
  267.     ocspBasicOCSPResponse *basic;    /* when type is id-pkix-ocsp-basic */
  268.     } decodedResponse;            /* local; not part of encoding */
  269. };
  270.  
  271. /*
  272.  * A BasicOCSPResponse -- when the responseType in a ResponseBytes is
  273.  * id-pkix-ocsp-basic, the "response" OCTET STRING above is the DER
  274.  * encoding of one of these.
  275.  *
  276.  * Note that in the OCSP specification, the signature fields are not
  277.  * part of a separate sub-structure.  But since they are the same fields
  278.  * as we define for the signature in a request, it made sense to share
  279.  * the C data structure here and in some shared code to operate on them.
  280.  */
  281. struct ocspBasicOCSPResponseStr {
  282.     ocspResponseData *tbsResponseData;    /* "tbs" == To Be Signed */
  283.     ocspSignature responseSignature;
  284. };
  285.  
  286. /*
  287.  * A ResponseData is the part of a BasicOCSPResponse that is signed
  288.  * (after it is DER encoded).  It contains the real details of the response
  289.  * (a per-certificate status).
  290.  */
  291. struct ocspResponseDataStr {
  292.     SECItem version;            /* an INTEGER */
  293.     SECItem derResponderID;
  294.     ocspResponderID *responderID;    /* local; not part of encoding */
  295.     SECItem producedAt;            /* a GeneralizedTime */
  296.     CERTOCSPSingleResponse **responses;
  297.     CERTCertExtension **responseExtensions;
  298. };
  299.  
  300. /*
  301.  * A ResponderID identifies the responder -- or more correctly, the
  302.  * signer of the response.  The ASN.1 definition of a ResponderID is:
  303.  *
  304.  * ResponderID    ::=    CHOICE {
  305.  *    byName            [1] EXPLICIT Name,
  306.  *    byKey            [2] EXPLICIT KeyHash }
  307.  *
  308.  * Because it is CHOICE, the type of identification used and the
  309.  * identification itself are actually encoded together.  To represent
  310.  * this same information internally, we explicitly define a type and
  311.  * save it, along with the value, into a data structure.
  312.  */
  313.  
  314. typedef enum {
  315.     ocspResponderID_byName,
  316.     ocspResponderID_byKey,
  317.     ocspResponderID_other        /* unknown kind of responderID */
  318. } ocspResponderIDType;
  319.  
  320. struct ocspResponderIDStr {
  321.     ocspResponderIDType responderIDType;/* local; not part of encoding */
  322.     union {
  323.     CERTName name;            /* when ocspResponderID_byName */
  324.     SECItem keyHash;        /* when ocspResponderID_byKey */
  325.     SECItem other;            /* when ocspResponderID_other */
  326.     } responderIDValue;
  327. };
  328.  
  329. /*
  330.  * The ResponseData in a BasicOCSPResponse contains a SEQUENCE OF
  331.  * SingleResponse -- one for each certificate whose status is being supplied.
  332.  * 
  333.  * XXX figure out how to get rid of that arena -- there must be a way
  334.  */
  335. struct CERTOCSPSingleResponseStr {
  336.     PRArenaPool *arena;            /* just a copy of the response arena,
  337.                      * needed here for extension handling
  338.                      * routines, on creation only */
  339.     CERTOCSPCertID *certID;
  340.     SECItem derCertStatus;
  341.     ocspCertStatus *certStatus;        /* local; not part of encoding */
  342.     SECItem thisUpdate;            /* a GeneralizedTime */
  343.     SECItem *nextUpdate;        /* a GeneralizedTime */
  344.     CERTCertExtension **singleExtensions;
  345. };
  346.  
  347. /*
  348.  * A CertStatus is the actual per-certificate status.  Its ASN.1 definition:
  349.  *
  350.  * CertStatus    ::=    CHOICE {
  351.  *    good            [0] IMPLICIT NULL,
  352.  *    revoked            [1] IMPLICIT RevokedInfo,
  353.  *    unknown            [2] IMPLICIT UnknownInfo }
  354.  *
  355.  * (where for now UnknownInfo is defined to be NULL but in the
  356.  * future may be replaced with an enumeration).
  357.  *
  358.  * Because it is CHOICE, the status value and its associated information
  359.  * (if any) are actually encoded together.  To represent this same
  360.  * information internally, we explicitly define a type and save it,
  361.  * along with the value, into a data structure.
  362.  */
  363.  
  364. typedef enum {
  365.     ocspCertStatus_good,        /* cert is not revoked */
  366.     ocspCertStatus_revoked,        /* cert is revoked */
  367.     ocspCertStatus_unknown,        /* cert was unknown to the responder */
  368.     ocspCertStatus_other        /* status was not an expected value */
  369. } ocspCertStatusType;
  370.  
  371. /*
  372.  * This is the actual per-certificate status.
  373.  *
  374.  * The "goodInfo" and "unknownInfo" items are only place-holders for a NULL.
  375.  * (Though someday OCSP may replace UnknownInfo with an enumeration that
  376.  * gives more detailed information.)
  377.  */
  378. struct ocspCertStatusStr {
  379.     ocspCertStatusType certStatusType;    /* local; not part of encoding */
  380.     union {
  381.     SECItem *goodInfo;        /* when ocspCertStatus_good */
  382.     ocspRevokedInfo *revokedInfo;    /* when ocspCertStatus_revoked */
  383.     SECItem *unknownInfo;        /* when ocspCertStatus_unknown */
  384.     SECItem *otherInfo;        /* when ocspCertStatus_other */
  385.     } certStatusInfo; 
  386. };
  387.  
  388. /*
  389.  * A RevokedInfo gives information about a revoked certificate -- when it
  390.  * was revoked and why.
  391.  */
  392. struct ocspRevokedInfoStr {
  393.     SECItem revocationTime;        /* a GeneralizedTime */
  394.     SECItem *revocationReason;        /* a CRLReason; ignored for now */
  395. };
  396.  
  397. /*
  398.  * ServiceLocator can be included as one of the singleRequestExtensions.
  399.  * When added, it specifies the (name of the) issuer of the cert being
  400.  * checked, and optionally the value of the AuthorityInfoAccess extension
  401.  * if the cert has one.
  402.  */
  403. struct ocspServiceLocatorStr {
  404.     CERTName *issuer;
  405.     SECItem locator;    /* DER encoded authInfoAccess extension from cert */
  406. };
  407.  
  408. #endif /* _OCSPTI_H_ */
  409.